Bitfield Struct
Procedural macro for bitfields that allows specifying bitfields as structs.
As this library provides a procedural macro, it has no runtime dependencies and works for no-std
environments.
- Supports bool flags, raw integers, and every custom type convertible into integers (structs/enums)
- Ideal for driver/OS/embedded development (defining HW registers/structures)
- Generates minimalistic, pure, safe rust functions
- Compile-time checks for type and field sizes
- Rust-analyzer friendly (carries over documentation to accessor functions)
- Exports field offsets and sizes as constants (useful for const asserts)
- Generation of
fmt::Debug
andDefault
Usage
Add this to your Cargo.toml
:
[]
= "0.5"
Basics
Let's begin with a simple example. Suppose we want to store multiple data inside a single Byte, as shown below:
This crate generates a nice wrapper type that makes it easy to do this:
use bitfield;
/// Define your type like this with the bitfield attribute
// The macro creates three accessor functions for each field:
// <name>, with_<name> and set_<name>
let my_byte = new
.with_kind
.with_system
.with_level
.with_present;
assert!;
Features
Additionally, this crate has a few useful features, which are shown here in more detail.
The example below shows how attributes are carried over and how signed integers, padding, and custom types are handled.
use bitfield;
/// A test bitfield with documentation
// <- Attributes after `bitfield` are carried over
/// A custom enum
// Usage:
let mut val = new
.with_int
.with_tiny
.with_negative
.with_custom
.with_public
// .with_read_only(true) <- Would not compile
.with_write_only;
println!;
let raw: u64 = val.into;
println!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
assert_eq!;
// const members
assert_eq!;
assert_eq!;
val.set_negative;
assert_eq!;
The macro generates three accessor functions for each field. Each accessor also inherits the documentation of its field.
The signatures for int
are:
use ;
// generated struct
;
// Also generates From<u64>, Into<u64>, Default, and Debug implementations...
Hint: You can use the rust-analyzer "Expand macro recursively" action to view the generated code.
Custom Types
The macro supports any types that are convertible into the underlying bitfield type. This can be enums like in the following example or any other struct.
The conversion and default values can be specified with the following #[bits]
parameters:
from
: Function converting from raw bits into the custom type, defaults to<ty>::from_bits
into
: Function converting from the custom type into raw bits, defaults to<ty>::into_bits
default
: Custom expression, defaults to calling<ty>::from_bits(0)
use bitfield;
Bit Order
The optional order
macro argument determines the layout of the bits, with the default being
Lsb (least significant bit) first:
use bitfield;
let my_byte_lsb = new
.with_kind
.with_system
.with_level
.with_present;
// .- present
// | .- level
// | | .- system
// | | | .- kind
assert!;
The macro generates the reverse order when Msb (most significant bit) is specified:
use bitfield;
let my_byte_msb = new
.with_kind
.with_system
.with_level
.with_present;
// .- kind
// | .- system
// | | .- level
// | | | .- present
assert!;
fmt::Debug
and Default
This macro automatically creates a suitable fmt::Debug
and Default
implementations similar to the ones created for normal structs by #[derive(Debug, Default)]
.
You can disable this with the extra debug
and default
arguments.
use ;
use bitfield;
let val = default;
println!